<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
                      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <meta http-equiv="content-type" content="text/html; charset=UTF-8"/>
    <title>Zend_Db_Table - Zend Framework Manual</title>

    <link href="../css/shCore.css" rel="stylesheet" type="text/css" />
    <link href="../css/shThemeDefault.css" rel="stylesheet" type="text/css" />
    <link href="../css/styles.css" media="all" rel="stylesheet" type="text/css" />
</head>
<body>
<h1>Zend Framework</h1>
<h2>Programmer's Reference Guide</h2>
<ul>
    <li><a href="../en/zend.db.table.html">Inglês (English)</a></li>
    <li><a href="../pt-br/zend.db.table.html">Português Brasileiro (Brazilian Portuguese)</a></li>
</ul>
<table width="100%">
    <tr valign="top">
        <td width="85%">
            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.db.select.html">Zend_Db_Select</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.db.html">Zend_Db</a></span><br />
                        <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.db.table.row.html">Zend_Db_Table_Row</a></div>
                    </td>
                </tr>
            </table>
<hr />
<div id="zend.db.table" class="section"><div class="info"><h1 class="title">Zend_Db_Table</h1></div>
    

    <div class="section" id="zend.db.table.introduction"><div class="info"><h1 class="title">Introduction</h1></div>
        

        <p class="para">
            The <span class="classname">Zend_Db_Table</span> class is an object-oriented interface to
            database tables. It provides methods for many common operations on tables. The base
            class is extensible, so you can add custom logic.
        </p>

        <p class="para">
            The <span class="classname">Zend_Db_Table</span> solution is an implementation of the
            <a href="http://www.martinfowler.com/eaaCatalog/tableDataGateway.html" class="link external">&raquo; Table Data
            Gateway</a> pattern. The solution also includes a class that implements the
            <a href="http://www.martinfowler.com/eaaCatalog/rowDataGateway.html" class="link external">&raquo; Row Data
            Gateway</a> pattern.
        </p>
    </div>

    <div class="section" id="zend.db.table.concrete"><div class="info"><h1 class="title">Using Zend_Db_Table as a concrete class</h1></div>
        

        <p class="para">
            As of Zend Framework 1.9, you can instantiate <span class="classname">Zend_Db_Table</span>. This
            added benefit is that you do not have to extend a base class and configure it to do
            simple operations such as selecting, inserting, updating and deleteing on a single
            table. below is an example of the simplest of use cases.
        </p>

        <div class="example" id="zend.db.table.defining.concrete-instantiation.example1"><div class="info"><p><b>Example #1 Declaring a table class with just the string name</b></p></div>
            

            <pre class="programlisting brush: php">
Zend_Db_Table::setDefaultAdapter($dbAdapter);
$bugTable = new Zend_Db_Table(&#039;bug&#039;);
</pre>

        </div>

        <p class="para">
            The above example represents the simplest of use cases. Make not of all the
            options describe below for configuring <span class="classname">Zend_Db_Table</span> tables. If
            you want to be able to use the concrete usage case, in addition to the more complex
            relationhip features, see the <span class="classname">Zend_Db_Table_Definition</span>
            documentation.
        </p>
    </div>

    <div class="section" id="zend.db.table.defining"><div class="info"><h1 class="title">Defining a Table Class</h1></div>
        

        <p class="para">
            For each table in your database that you want to access, define a class that extends
            <span class="classname">Zend_Db_Table_Abstract</span>.
        </p>

        <div class="section" id="zend.db.table.defining.table-schema"><div class="info"><h1 class="title">Defining the Table Name and Schema</h1></div>
            

            <p class="para">
                Declare the database table for which this class is defined, using the protected
                variable <var class="varname">$_name</var>. This is a string, and must contain the name of
                the table spelled as it appears in the database.
            </p>

            <div class="example" id="zend.db.table.defining.table-schema.example1"><div class="info"><p><b>Example #2 Declaring a table class with explicit table name</b></p></div>
                

                <pre class="programlisting brush: php">
class Bugs extends Zend_Db_Table_Abstract
{
    protected $_name = &#039;bugs&#039;;
}
</pre>

            </div>

            <p class="para">
                If you don&#039;t specify the table name, it defaults to the name of the class. If you
                rely on this default, the class name must match the spelling of the table name as
                it appears in the database.
            </p>

            <div class="example" id="zend.db.table.defining.table-schema.example"><div class="info"><p><b>Example #3 Declaring a table class with implicit table name</b></p></div>
                

                <pre class="programlisting brush: php">
class bugs extends Zend_Db_Table_Abstract
{
    // table name matches class name
}
</pre>

            </div>

            <p class="para">
                You can also declare the schema for the table, either with the protected variable
                <var class="varname">$_schema</var>, or with the schema prepended to the table name in the
                <var class="varname">$_name</var> property. Any schema specified with the
                <var class="varname">$_name</var> property takes precedence over a schema specified with the
                <var class="varname">$_schema</var> property. In some <acronym class="acronym">RDBMS</acronym> brands, the
                term for schema is &quot;database&quot; or &quot;tablespace,&quot; but it is used similarly.
            </p>

            <div class="example" id="zend.db.table.defining.table-schema.example3"><div class="info"><p><b>Example #4 Declaring a table class with schema</b></p></div>
                

                <pre class="programlisting brush: php">
// First alternative:
class Bugs extends Zend_Db_Table_Abstract
{
    protected $_schema = &#039;bug_db&#039;;
    protected $_name   = &#039;bugs&#039;;
}

// Second alternative:
class Bugs extends Zend_Db_Table_Abstract
{
    protected $_name = &#039;bug_db.bugs&#039;;
}

// If schemas are specified in both $_name and $_schema, the one
// specified in $_name takes precedence:

class Bugs extends Zend_Db_Table_Abstract
{
    protected $_name   = &#039;bug_db.bugs&#039;;
    protected $_schema = &#039;ignored&#039;;
}
</pre>

            </div>

            <p class="para">
                The schema and table names may also be specified via constructor configuration
                directives, which override any default values specified with the
                <var class="varname">$_name</var> and <var class="varname">$_schema</var> properties. A schema
                specification given with the <span class="property">name</span> directive overrides any value
                provided with the <span class="property">schema</span> option.
            </p>

            <div class="example" id="zend.db.table.defining.table-schema.example.constructor"><div class="info"><p><b>Example #5 Declaring table and schema names upon instantiation</b></p></div>
                

                <pre class="programlisting brush: php">
class Bugs extends Zend_Db_Table_Abstract
{
}

// First alternative:

$tableBugs = new Bugs(array(&#039;name&#039; =&gt; &#039;bugs&#039;, &#039;schema&#039; =&gt; &#039;bug_db&#039;));

// Second alternative:

$tableBugs = new Bugs(array(&#039;name&#039; =&gt; &#039;bug_db.bugs&#039;));

// If schemas are specified in both &#039;name&#039; and &#039;schema&#039;, the one
// specified in &#039;name&#039; takes precedence:

$tableBugs = new Bugs(array(&#039;name&#039; =&gt; &#039;bug_db.bugs&#039;,
                            &#039;schema&#039; =&gt; &#039;ignored&#039;));
</pre>

            </div>

            <p class="para">
                If you don&#039;t specify the schema name, it defaults to the schema to which your
                database adapter instance is connected.
            </p>
        </div>

        <div class="section" id="zend.db.table.defining.primary-key"><div class="info"><h1 class="title">Defining the Table Primary Key</h1></div>
            

            <p class="para">
                Every table must have a primary key. You can declare the column for the primary key
                using the protected variable <var class="varname">$_primary</var>. This is either a string
                that names the single column for the primary key, or else it is an array of column
                names if your primary key is a compound key.
            </p>

            <div class="example" id="zend.db.table.defining.primary-key.example"><div class="info"><p><b>Example #6 Example of specifying the primary key</b></p></div>
                

                <pre class="programlisting brush: php">
class Bugs extends Zend_Db_Table_Abstract
{
    protected $_name = &#039;bugs&#039;;
    protected $_primary = &#039;bug_id&#039;;
}
</pre>

            </div>

            <p class="para">
                If you don&#039;t specify the primary key, <span class="classname">Zend_Db_Table_Abstract</span>
                tries to discover the primary key based on the information provided by the
                 <span class="methodname">describeTable()</span>´ method.
            </p>

            <blockquote class="note"><p><b class="note">Note</b>: 
                <p class="para">
                    Every table class must know which columns can be used to address rows
                    uniquely. If no primary key columns are specified in the table class
                    definition or the table constructor arguments, or discovered in the table
                    metadata provided by  <span class="methodname">describeTable()</span>, then the table
                    cannot be used with <span class="classname">Zend_Db_Table</span>.
                </p>
            </p></blockquote>
        </div>

        <div class="section" id="zend.db.table.defining.setup"><div class="info"><h1 class="title">Overriding Table Setup Methods</h1></div>
            

            <p class="para">
                When you create an instance of a Table class, the constructor calls a set of
                protected methods that initialize metadata for the table. You can extend any of
                these methods to define metadata explicitly. Remember to call the method of the
                same name in the parent class at the end of your method.
            </p>

            <div class="example" id="zend.db.table.defining.setup.example"><div class="info"><p><b>Example #7 Example of overriding the _setupTableName() method</b></p></div>
                

                <pre class="programlisting brush: php">
class Bugs extends Zend_Db_Table_Abstract
{
    protected function _setupTableName()
    {
        $this-&gt;_name = &#039;bugs&#039;;
        parent::_setupTableName();
    }
}
</pre>

            </div>

            <p class="para">
                The setup methods you can override are the following:
            </p>

            <ul class="itemizedlist">
                <li class="listitem">
                    <p class="para">
                         <span class="methodname">_setupDatabaseAdapter()</span> checks that an adapter has
                        been provided; gets a default adapter from the registry if needed. By
                        overriding this method, you can set a database adapter from some other
                        source.
                    </p>
                </li>

                <li class="listitem">
                    <p class="para">
                         <span class="methodname">_setupTableName()</span> defaults the table name to the
                        name of the class. By overriding this method, you can set the table name
                        before this default behavior runs.
                    </p>
                </li>

                <li class="listitem">
                    <p class="para">
                         <span class="methodname">_setupMetadata()</span> sets the schema if the table name
                        contains the pattern &quot;<strong class="command">schema.table</strong>&quot;; calls
                         <span class="methodname">describeTable()</span> to get metadata information;
                        defaults the <var class="varname">$_cols</var> array to the columns reported by
                         <span class="methodname">describeTable()</span>. By overriding this method, you can
                        specify the columns.
                    </p>
                </li>

                <li class="listitem">
                    <p class="para">
                         <span class="methodname">_setupPrimaryKey()</span> defaults the primary key columns
                        to those reported by  <span class="methodname">describeTable()</span>; checks that
                        the primary key columns are included in the <var class="varname">$_cols</var> array.
                        By overriding this method, you can specify the primary key columns.
                    </p>
                </li>
            </ul>
        </div>

        <div class="section" id="zend.db.table.initialization"><div class="info"><h1 class="title">Table initialization</h1></div>
            

            <p class="para">
                If application-specific logic needs to be initialized when a Table class is
                constructed, you can select to move your tasks to the
                 <span class="methodname">init()</span> method, which is called after all Table metadata has
                been processed. This is recommended over the  <span class="methodname">__construct()</span>
                method if you do not need to alter the metadata in any programmatic way.
            </p>

            <div class="example" id="zend.db.table.defining.init.usage.example"><div class="info"><p><b>Example #8 Example usage of init() method</b></p></div>
                

                <pre class="programlisting brush: php">
class Bugs extends Zend_Db_Table_Abstract
{
    protected $_observer;

    public function init()
    {
        $this-&gt;_observer = new MyObserverClass();
    }
}
</pre>

            </div>
        </div>
    </div>

    <div class="section" id="zend.db.table.constructing"><div class="info"><h1 class="title">Creating an Instance of a Table</h1></div>
        

        <p class="para">
            Before you use a Table class, create an instance using its constructor. The
            constructor&#039;s argument is an array of options. The most important option to a Table
            constructor is the database adapter instance, representing a live connection to an
            <acronym class="acronym">RDBMS</acronym>. There are three ways of specifying the database adapter to a
            Table class, and these three ways are described below:
        </p>

        <div class="section" id="zend.db.table.constructing.adapter"><div class="info"><h1 class="title">Specifying a Database Adapter</h1></div>
            

            <p class="para">
                The first way to provide a database adapter to a Table class is by passing it as an
                object of type <span class="classname">Zend_Db_Adapter_Abstract</span> in the options array,
                identified by the key &#039;<span class="property">db</span>&#039;.
            </p>

            <div class="example" id="zend.db.table.constructing.adapter.example"><div class="info"><p><b>Example #9 Example of constructing a Table using an Adapter object</b></p></div>
                

                <pre class="programlisting brush: php">
$db = Zend_Db::factory(&#039;PDO_MYSQL&#039;, $options);

$table = new Bugs(array(&#039;db&#039; =&gt; $db));
</pre>

            </div>
        </div>

        <div class="section" id="zend.db.table.constructing.default-adapter"><div class="info"><h1 class="title">Setting a Default Database Adapter</h1></div>
            

            <p class="para">
                The second way to provide a database adapter to a Table class is by declaring an
                object of type <span class="classname">Zend_Db_Adapter_Abstract</span> to be a default
                database adapter for all subsequent instances of Tables in your application. You can
                do this with the static method
                 <span class="methodname">Zend_Db_Table_Abstract::setDefaultAdapter()</span>. The argument
                is an object of type <span class="classname">Zend_Db_Adapter_Abstract</span>.
            </p>

            <div class="example" id="zend.db.table.constructing.default-adapter.example"><div class="info"><p><b>Example #10 Example of constructing a Table using a the Default Adapter</b></p></div>
                

                <pre class="programlisting brush: php">
$db = Zend_Db::factory(&#039;PDO_MYSQL&#039;, $options);
Zend_Db_Table_Abstract::setDefaultAdapter($db);

// Later...

$table = new Bugs();
</pre>

            </div>

            <p class="para">
                It can be convenient to create the database adapter object in a central place of
                your application, such as the bootstrap, and then store it as the default adapter.
                This gives you a means to ensure that the adapter instance is the same throughout
                your application. However, setting a default adapter is limited to a single adapter
                instance.
            </p>
        </div>

        <div class="section" id="zend.db.table.constructing.registry"><div class="info"><h1 class="title">Storing a Database Adapter in the Registry</h1></div>
            

            <p class="para">
                The third way to provide a database adapter to a Table class is by passing a string
                in the options array, also identified by the &#039;<span class="property">db</span>&#039; key. The
                string is used as a key to the static <span class="classname">Zend_Registry</span> instance,
                where the entry at that key is an object of type
                <span class="classname">Zend_Db_Adapter_Abstract</span>.
            </p>

            <div class="example" id="zend.db.table.constructing.registry.example"><div class="info"><p><b>Example #11 Example of constructing a Table using a Registry key</b></p></div>
                

                <pre class="programlisting brush: php">
$db = Zend_Db::factory(&#039;PDO_MYSQL&#039;, $options);
Zend_Registry::set(&#039;my_db&#039;, $db);

// Later...

$table = new Bugs(array(&#039;db&#039; =&gt; &#039;my_db&#039;));
</pre>

            </div>

            <p class="para">
                Like setting the default adapter, this gives you the means to ensure that the same
                adapter instance is used throughout your application. Using the registry is more
                flexible, because you can store more than one adapter instance. A given adapter
                instance is specific to a certain <acronym class="acronym">RDBMS</acronym> brand and database
                instance. If your application needs access to multiple databases or even multiple
                database brands, then you need to use multiple adapters.
            </p>
        </div>
    </div>

    <div class="section" id="zend.db.table.insert"><div class="info"><h1 class="title">Inserting Rows to a Table</h1></div>
        

        <p class="para">
            You can use the Table object to insert rows into the database table on which the Table
            object is based. Use the  <span class="methodname">insert()</span> method of your Table object.
            The argument is an associative array, mapping column names to values.
        </p>

        <div class="example" id="zend.db.table.insert.example"><div class="info"><p><b>Example #12 Example of inserting to a Table</b></p></div>
            

            <pre class="programlisting brush: php">
$table = new Bugs();

$data = array(
    &#039;created_on&#039;      =&gt; &#039;2007-03-22&#039;,
    &#039;bug_description&#039; =&gt; &#039;Something wrong&#039;,
    &#039;bug_status&#039;      =&gt; &#039;NEW&#039;
);

$table-&gt;insert($data);
</pre>

        </div>

        <p class="para">
            By default, the values in your data array are inserted as literal values, using
            parameters. If you need them to be treated as <acronym class="acronym">SQL</acronym> expressions, you
            must make sure they are distinct from plain strings. Use an object of type
            <span class="classname">Zend_Db_Expr</span> to do this.
        </p>

        <div class="example" id="zend.db.table.insert.example-expr"><div class="info"><p><b>Example #13 Example of inserting expressions to a Table</b></p></div>
            

            <pre class="programlisting brush: php">
$table = new Bugs();

$data = array(
    &#039;created_on&#039;      =&gt; new Zend_Db_Expr(&#039;CURDATE()&#039;),
    &#039;bug_description&#039; =&gt; &#039;Something wrong&#039;,
    &#039;bug_status&#039;      =&gt; &#039;NEW&#039;
);
</pre>

        </div>

        <p class="para">
            In the examples of inserting rows above, it is assumed that the table has an
            auto-incrementing primary key. This is the default behavior of
            <span class="classname">Zend_Db_Table_Abstract</span>, but there are other types of primary keys
            as well. The following sections describe how to support different types of primary keys.
        </p>

        <div class="section" id="zend.db.table.insert.key-auto"><div class="info"><h1 class="title">Using a Table with an Auto-incrementing Key</h1></div>
            

            <p class="para">
                An auto-incrementing primary key generates a unique integer value for you if you
                omit the primary key column from your <acronym class="acronym">SQL</acronym>
                <b><tt>INSERT</tt></b> statement.
            </p>

            <p class="para">
                In <span class="classname">Zend_Db_Table_Abstract</span>, if you define the protected
                variable <var class="varname">$_sequence</var> to be the Boolean value
                <b><tt>TRUE</tt></b>, then the class assumes that the table has an
                auto-incrementing primary key.
            </p>

            <div class="example" id="zend.db.table.insert.key-auto.example"><div class="info"><p><b>Example #14 Example of declaring a Table with auto-incrementing primary key</b></p></div>
                

                <pre class="programlisting brush: php">
class Bugs extends Zend_Db_Table_Abstract
{
    protected $_name = &#039;bugs&#039;;

    // This is the default in the Zend_Db_Table_Abstract class;
    // you do not need to define this.
    protected $_sequence = true;
}
</pre>

            </div>

            <p class="para">
                MySQL, Microsoft <acronym class="acronym">SQL</acronym> Server, and SQLite are examples of
                <acronym class="acronym">RDBMS</acronym> brands that support auto-incrementing primary keys.
            </p>

            <p class="para">
                PostgreSQL has a <b><tt>SERIAL</tt></b> notation that implicitly defines a
                sequence based on the table and column name, and uses the sequence to generate key
                values for new rows. <acronym class="acronym">IBM</acronym> <acronym class="acronym">DB2</acronym> has an
                <b><tt>IDENTITY</tt></b> notation that works similarly. If you use either of
                these notations, treat your <span class="classname">Zend_Db_Table</span> class as having an
                auto-incrementing column with respect to declaring the <var class="varname">$_sequence</var>
                member as <b><tt>TRUE</tt></b>.
            </p>
        </div>

        <div class="section" id="zend.db.table.insert.key-sequence"><div class="info"><h1 class="title">Using a Table with a Sequence</h1></div>
            

            <p class="para">
                A sequence is a database object that generates a unique value, which can be used
                as a primary key value in one or more tables of the database.
            </p>

            <p class="para">
                If you define <var class="varname">$_sequence</var> to be a string, then
                <span class="classname">Zend_Db_Table_Abstract</span> assumes the string to name a sequence
                object in the database. The sequence is invoked to generate a new value, and this
                value is used in the <b><tt>INSERT</tt></b> operation.
            </p>

            <div class="example" id="zend.db.table.insert.key-sequence.example"><div class="info"><p><b>Example #15 Example of declaring a Table with a sequence</b></p></div>
                

                <pre class="programlisting brush: php">
class Bugs extends Zend_Db_Table_Abstract
{
    protected $_name = &#039;bugs&#039;;

    protected $_sequence = &#039;bug_sequence&#039;;
}
</pre>

            </div>

            <p class="para">
                Oracle, PostgreSQL, and <acronym class="acronym">IBM</acronym> <acronym class="acronym">DB2</acronym> are examples
                of <acronym class="acronym">RDBMS</acronym> brands that support sequence objects in the database.
            </p>

            <p class="para">
                PostgreSQL and <acronym class="acronym">IBM</acronym> <acronym class="acronym">DB2</acronym> also have syntax that
                defines sequences implicitly and associated with columns. If you use this notation,
                treat the table as having an auto-incrementing key column. Define the sequence name
                as a string only in cases where you would invoke the sequence explicitly to get the
                next key value.
            </p>
        </div>

        <div class="section" id="zend.db.table.insert.key-natural"><div class="info"><h1 class="title">Using a Table with a Natural Key</h1></div>
            

            <p class="para">
                Some tables have a natural key. This means that the key is not automatically
                generated by the table or by a sequence. You must specify the value for the primary
                key in this case.
            </p>

            <p class="para">
                If you define the <var class="varname">$_sequence</var> to be the Boolean value
                <b><tt>FALSE</tt></b>, then <span class="classname">Zend_Db_Table_Abstract</span>
                assumes that the table has a natural primary key. You must provide values for the
                primary key columns in the array of data to the  <span class="methodname">insert()</span>
                method, or else this method throws a <span class="classname">Zend_Db_Table_Exception</span>.
            </p>

            <div class="example" id="zend.db.table.insert.key-natural.example"><div class="info"><p><b>Example #16 Example of declaring a Table with a natural key</b></p></div>
                

                <pre class="programlisting brush: php">
class BugStatus extends Zend_Db_Table_Abstract
{
    protected $_name = &#039;bug_status&#039;;

    protected $_sequence = false;
}
</pre>

            </div>

            <blockquote class="note"><p><b class="note">Note</b>: 
                <p class="para">
                    All <acronym class="acronym">RDBMS</acronym> brands support tables with natural keys. Examples
                    of tables that are often declared as having natural keys are lookup tables,
                    intersection tables in many-to-many relationships, or most tables with compound
                    primary keys.
                </p>
            </p></blockquote>
        </div>
    </div>

    <div class="section" id="zend.db.table.update"><div class="info"><h1 class="title">Updating Rows in a Table</h1></div>
        

        <p class="para">
            You can update rows in a database table using the  <span class="methodname">update()</span>
            method of a Table class. This method takes two arguments: an associative array of
            columns to change and new values to assign to these columns; and an
            <acronym class="acronym">SQL</acronym> expression that is used in a <b><tt>WHERE</tt></b> clause,
            as criteria for the rows to change in the <b><tt>UPDATE</tt></b> operation.
        </p>

        <div class="example" id="zend.db.table.update.example"><div class="info"><p><b>Example #17 Example of updating rows in a Table</b></p></div>
            

            <pre class="programlisting brush: php">
$table = new Bugs();

$data = array(
    &#039;updated_on&#039;      =&gt; &#039;2007-03-23&#039;,
    &#039;bug_status&#039;      =&gt; &#039;FIXED&#039;
);

$where = $table-&gt;getAdapter()-&gt;quoteInto(&#039;bug_id = ?&#039;, 1234);

$table-&gt;update($data, $where);
</pre>

        </div>

        <p class="para">
            Since the table  <span class="methodname">update()</span> method proxies to the database adapter
            <a href="zend.db.adapter.html#zend.db.adapter.write.update" class="link"> <span class="methodname">update()</span></a>
            method, the second argument can be an array of <acronym class="acronym">SQL</acronym> expressions. The
            expressions are combined as Boolean terms using an <b><tt>AND</tt></b> operator.
        </p>

        <blockquote class="note"><p><b class="note">Note</b>: 
            <p class="para">
                The values and identifiers in the <acronym class="acronym">SQL</acronym> expression are not quoted
                for you. If you have values or identifiers that require quoting, you are responsible
                for doing this. Use the  <span class="methodname">quote()</span>,
                 <span class="methodname">quoteInto()</span>, and  <span class="methodname">quoteIdentifier()</span>
                methods of the database adapter.
            </p>
        </p></blockquote>
    </div>

    <div class="section" id="zend.db.table.delete"><div class="info"><h1 class="title">Deleting Rows from a Table</h1></div>
        

        <p class="para">
            You can delete rows from a database table using the  <span class="methodname">delete()</span>
            method. This method takes one argument, which is an <acronym class="acronym">SQL</acronym> expression
            that is used in a <b><tt>WHERE</tt></b> clause, as criteria for the rows to delete.
        </p>

        <div class="example" id="zend.db.table.delete.example"><div class="info"><p><b>Example #18 Example of deleting rows from a Table</b></p></div>
            

            <pre class="programlisting brush: php">
$table = new Bugs();

$where = $table-&gt;getAdapter()-&gt;quoteInto(&#039;bug_id = ?&#039;, 1235);

$table-&gt;delete($where);
</pre>

        </div>

        <p class="para">
            Since the table  <span class="methodname">delete()</span> method proxies to the database adapter
            <a href="zend.db.adapter.html#zend.db.adapter.write.delete" class="link"> <span class="methodname">delete()</span></a>
            method, the argument can also be an array of <acronym class="acronym">SQL</acronym> expressions. The
            expressions are combined as Boolean terms using an <b><tt>AND</tt></b> operator.
        </p>

        <blockquote class="note"><p><b class="note">Note</b>: 
            <p class="para">
                The values and identifiers in the <acronym class="acronym">SQL</acronym> expression are not quoted
                for you. If you have values or identifiers that require quoting, you are responsible
                for doing this. Use the  <span class="methodname">quote()</span>,
                 <span class="methodname">quoteInto()</span>, and  <span class="methodname">quoteIdentifier()</span>
                methods of the database adapter.
            </p>
        </p></blockquote>
    </div>

    <div class="section" id="zend.db.table.find"><div class="info"><h1 class="title">Finding Rows by Primary Key</h1></div>
        

        <p class="para">
            You can query the database table for rows matching specific values in the primary key,
            using the  <span class="methodname">find()</span> method. The first argument of this method is
            either a single value or an array of values to match against the primary key of the
            table.
        </p>

        <div class="example" id="zend.db.table.find.example"><div class="info"><p><b>Example #19 Example of finding rows by primary key values</b></p></div>
            

            <pre class="programlisting brush: php">
$table = new Bugs();

// Find a single row
// Returns a Rowset
$rows = $table-&gt;find(1234);

// Find multiple rows
// Also returns a Rowset
$rows = $table-&gt;find(array(1234, 5678));
</pre>

        </div>

        <p class="para">
            If you specify a single value, the method returns at most one row, because a primary
            key cannot have duplicate values and there is at most one row in the database table
            matching the value you specify. If you specify multiple values in an array, the method
            returns at most as many rows as the number of distinct values you specify.
        </p>

        <p class="para">
            The  <span class="methodname">find()</span> method might return fewer rows than the number of
            values you specify for the primary key, if some of the values don&#039;t match any rows in
            the database table. The method even may return zero rows. Because the number of rows
            returned is variable, the  <span class="methodname">find()</span> method returns an object of
            type <span class="classname">Zend_Db_Table_Rowset_Abstract</span>.
        </p>

        <p class="para">
            If the primary key is a compound key, that is, it consists of multiple columns, you can
            specify the additional columns as additional arguments to the
             <span class="methodname">find()</span> method. You must provide as many arguments as the number
            of columns in the table&#039;s primary key.
        </p>

        <p class="para">
            To find multiple rows from a table with a compound primary key, provide an array for
            each of the arguments. All of these arrays must have the same number of elements. The
            values in each array are formed into tuples in order; for example, the first element
            in all the array arguments define the first compound primary key value, then the second
            elements of all the arrays define the second compound primary key value, and so on.
        </p>

        <div class="example" id="zend.db.table.find.example-compound"><div class="info"><p><b>Example #20 Example of finding rows by compound primary key values</b></p></div>
            

            <div class="example-contents"><p>
                The call to  <span class="methodname">find()</span> below to match multiple rows can match
                two rows in the database. The first row must have primary key value (1234, &#039;ABC&#039;),
                and the second row must have primary key value (5678, &#039;DEF&#039;).
            </p></div>

            <pre class="programlisting brush: php">
class BugsProducts extends Zend_Db_Table_Abstract
{
    protected $_name = &#039;bugs_products&#039;;
    protected $_primary = array(&#039;bug_id&#039;, &#039;product_id&#039;);
}

$table = new BugsProducts();

// Find a single row with a compound primary key
// Returns a Rowset
$rows = $table-&gt;find(1234, &#039;ABC&#039;);

// Find multiple rows with compound primary keys
// Also returns a Rowset
$rows = $table-&gt;find(array(1234, 5678), array(&#039;ABC&#039;, &#039;DEF&#039;));
</pre>

        </div>
    </div>

    <div class="section" id="zend.db.table.fetch-all"><div class="info"><h1 class="title">Querying for a Set of Rows</h1></div>
        

        <div class="section" id="zend.db.table.fetch-all.select"><div class="info"><h1 class="title">Select API</h1></div>
            

            <div class="warning"><b class="warning">Warning</b>
                <p class="para">
                    The <acronym class="acronym">API</acronym> for fetch operations has been superseded to allow
                    a <span class="classname">Zend_Db_Table_Select</span> object to modify the query.
                    However, the deprecated usage of the  <span class="methodname">fetchRow()</span> and
                     <span class="methodname">fetchAll()</span> methods will continue to work without
                    modification.
                </p>

                <p class="para">
                    The following statements are all legal and functionally identical, however
                    it is recommended to update your code to take advantage of the new usage
                    where possible.
                </p>

                <pre class="programlisting brush: php">
/**
 * Fetching a rowset
 */
$rows = $table-&gt;fetchAll(
    &#039;bug_status = &quot;NEW&quot;&#039;,
    &#039;bug_id ASC&#039;,
    10,
    0
    );
$rows = $table-&gt;fetchAll(
    $table-&gt;select()
        -&gt;where(&#039;bug_status = ?&#039;, &#039;NEW&#039;)
        -&gt;order(&#039;bug_id ASC&#039;)
        -&gt;limit(10, 0)
    );
// or with binding
$rows = $table-&gt;fetchAll(
    $table-&gt;select()
        -&gt;where(&#039;bug_status = :status&#039;)
        -&gt;bind(array(&#039;:status&#039;=&gt;&#039;NEW&#039;)
        -&gt;order(&#039;bug_id ASC&#039;)
        -&gt;limit(10, 0)
    );

/**
 * Fetching a single row
 */
$row = $table-&gt;fetchRow(
    &#039;bug_status = &quot;NEW&quot;&#039;,
    &#039;bug_id ASC&#039;
    );
$row = $table-&gt;fetchRow(
    $table-&gt;select()
        -&gt;where(&#039;bug_status = ?&#039;, &#039;NEW&#039;)
        -&gt;order(&#039;bug_id ASC&#039;)
    );
// or with binding
$row = $table-&gt;fetchRow(
    $table-&gt;select()
        -&gt;where(&#039;bug_status = :status&#039;)
        -&gt;bind(array(&#039;:status&#039;=&gt;&#039;NEW&#039;)
        -&gt;order(&#039;bug_id ASC&#039;)
    );
</pre>

            </div>

            <p class="para">
                The <span class="classname">Zend_Db_Table_Select</span> object is an extension of the
                <span class="classname">Zend_Db_Select</span> object that applies specific restrictions to
                a query. The enhancements and restrictions are:
            </p>

            <ul class="itemizedlist">
                <li class="listitem">
                    <p class="para">
                        You <em class="emphasis">can</em> elect to return a subset of columns within a
                        fetchRow or fetchAll query. This can provide optimization benefits where
                        returning a large set of results for all columns is not desirable.
                    </p>
                </li>

                <li class="listitem">
                    <p class="para">
                        You <em class="emphasis">can</em> specify columns that evaluate expressions from
                        within the selected table. However this will mean that the returned row or
                        rowset will be <span class="property">readOnly</span> and cannot be used for
                         <span class="methodname">save()</span> operations. A
                        <span class="classname">Zend_Db_Table_Row</span> with
                        <span class="property">readOnly</span> status will throw an exception if a
                         <span class="methodname">save()</span> operation is attempted.
                    </p>
                </li>

                <li class="listitem">
                    <p class="para">
                        You <em class="emphasis">can</em> allow <b><tt>JOIN</tt></b> clauses on a
                        select to allow multi-table lookups.
                    </p>
                </li>

                <li class="listitem">
                    <p class="para">
                        You <em class="emphasis">can not</em> specify columns from a JOINed tabled to be
                        returned in a row or rowset. Doing so will trigger a <acronym class="acronym">PHP</acronym>
                        error. This was done to ensure the integrity of the
                        <span class="classname">Zend_Db_Table</span> is retained. i.e. A
                        <span class="classname">Zend_Db_Table_Row</span> should only reference columns
                        derived from its parent table.
                    </p>
                </li>
            </ul>

            <div class="example" id="zend.db.table.qry.rows.set.simple.usage.example"><div class="info"><p><b>Example #21 Simple usage</b></p></div>
                

                <pre class="programlisting brush: php">
$table = new Bugs();

$select = $table-&gt;select();
$select-&gt;where(&#039;bug_status = ?&#039;, &#039;NEW&#039;);

$rows = $table-&gt;fetchAll($select);
</pre>

            </div>

            <p class="para">
                Fluent interfaces are implemented across the component, so this can be rewritten
                this in a more abbreviated form.
            </p>

            <div class="example" id="zend.db.table.qry.rows.set.fluent.interface.example"><div class="info"><p><b>Example #22 Example of fluent interface</b></p></div>
                

                <pre class="programlisting brush: php">
$table = new Bugs();

$rows =
    $table-&gt;fetchAll($table-&gt;select()-&gt;where(&#039;bug_status = ?&#039;, &#039;NEW&#039;));
</pre>

            </div>
        </div>

        <div class="section" id="zend.db.table.fetch-all.usage"><div class="info"><h1 class="title">Fetching a rowset</h1></div>
            

            <p class="para">
                You can query for a set of rows using any criteria other than the primary key
                values, using the  <span class="methodname">fetchAll()</span> method of the Table class.
                This method returns an object of type
                <span class="classname">Zend_Db_Table_Rowset_Abstract</span>.
            </p>

            <div class="example" id="zend.db.table.qry.rows.set.finding.row.example"><div class="info"><p><b>Example #23 Example of finding rows by an expression</b></p></div>
                

                <pre class="programlisting brush: php">
$table = new Bugs();

$select = $table-&gt;select()-&gt;where(&#039;bug_status = ?&#039;, &#039;NEW&#039;);

$rows = $table-&gt;fetchAll($select);
</pre>

            </div>

            <p class="para">
                You may also pass sorting criteria in an <b><tt>ORDER</tt></b> BY clause, as
                well as count and offset integer values, used to make the query return a specific
                subset of rows. These values are used in a <b><tt>LIMIT</tt></b> clause, or in
                equivalent logic for <acronym class="acronym">RDBMS</acronym> brands that do not support the
                <b><tt>LIMIT</tt></b> syntax.
            </p>

            <div class="example" id="zend.db.table.fetch-all.example2"><div class="info"><p><b>Example #24 Example of finding rows by an expression</b></p></div>
                

                <pre class="programlisting brush: php">
$table = new Bugs();

$order  = &#039;bug_id&#039;;

// Return the 21st through 30th rows
$count  = 10;
$offset = 20;

$select = $table-&gt;select()-&gt;where(&#039;bug_status = ?&#039;, &#039;NEW&#039;)
                          -&gt;order($order)
                          -&gt;limit($count, $offset);

$rows = $table-&gt;fetchAll($select);
</pre>

            </div>

            <p class="para">
                All of the arguments above are optional. If you omit the <b><tt>ORDER</tt></b>
                clause, the result set includes rows from the table in an unpredictable order. If
                no <b><tt>LIMIT</tt></b> clause is set, you retrieve every row in the table
                that matches the <b><tt>WHERE</tt></b> clause.
            </p>
        </div>

        <div class="section" id="zend.db.table.advanced.usage"><div class="info"><h1 class="title">Advanced usage</h1></div>
            

            <p class="para">
                For more specific and optimized requests, you may wish to limit the number of
                columns returned in a row or rowset. This can be achieved by passing a
                <b><tt>FROM</tt></b> clause to the select object. The first argument in the
                <b><tt>FROM</tt></b> clause is identical to that of a
                <span class="classname">Zend_Db_Select</span> object with the addition of being able to pass
                an instance of <span class="classname">Zend_Db_Table_Abstract</span> and have it
                automatically determine the table name.
            </p>

            <div class="example" id="zend.db.table.qry.rows.set.retrieving.a.example"><div class="info"><p><b>Example #25 Retrieving specific columns</b></p></div>
                

                <pre class="programlisting brush: php">
$table = new Bugs();

$select = $table-&gt;select();
$select-&gt;from($table, array(&#039;bug_id&#039;, &#039;bug_description&#039;))
       -&gt;where(&#039;bug_status = ?&#039;, &#039;NEW&#039;);

$rows = $table-&gt;fetchAll($select);
</pre>

            </div>

            <div class="important"><b class="important">Important</b>
                <p class="para">
                    The rowset contains rows that are still &#039;valid&#039; - they simply contain a
                    subset of the columns of a table. If a  <span class="methodname">save()</span>
                    method is called on a partial row then only the fields available will be
                    modified.
                </p>
            </div>

            <p class="para">
                You can also specify expressions within a <b><tt>FROM</tt></b> clause and have
                these returned as a readOnly row or rowset. In this example we will return a rows
                from the bugs table that show an aggregate of the number of new bugs reported by
                individuals. Note the <b><tt>GROUP</tt></b> clause. The &#039;count&#039; column will be
                made available to the row for evaluation and can be accessed as if it were part of
                the schema.
            </p>

            <div class="example" id="zend.db.table.qry.rows.set.retrieving.b.example"><div class="info"><p><b>Example #26 Retrieving expressions as columns</b></p></div>
                

                <pre class="programlisting brush: php">
$table = new Bugs();

$select = $table-&gt;select();
$select-&gt;from($table,
              array(&#039;COUNT(reported_by) as `count`&#039;, &#039;reported_by&#039;))
       -&gt;where(&#039;bug_status = ?&#039;, &#039;NEW&#039;)
       -&gt;group(&#039;reported_by&#039;);

$rows = $table-&gt;fetchAll($select);
</pre>

            </div>

            <p class="para">
                You can also use a lookup as part of your query to further refine your fetch
                operations. In this example the accounts table is queried as part of a search for
                all new bugs reported by &#039;Bob&#039;.
            </p>

            <div class="example" id="zend.db.table.qry.rows.set.refine.example"><div class="info"><p><b>Example #27 Using a lookup table to refine the results of fetchAll()</b></p></div>
                

                <pre class="programlisting brush: php">
$table = new Bugs();

// retrieve with from part set, important when joining
$select = $table-&gt;select(Zend_Db_Table::SELECT_WITH_FROM_PART);
$select-&gt;setIntegrityCheck(false)
       -&gt;where(&#039;bug_status = ?&#039;, &#039;NEW&#039;)
       -&gt;join(&#039;accounts&#039;, &#039;accounts.account_name = bugs.reported_by&#039;)
       -&gt;where(&#039;accounts.account_name = ?&#039;, &#039;Bob&#039;);

$rows = $table-&gt;fetchAll($select);
</pre>

            </div>

            <p class="para">
                The <span class="classname">Zend_Db_Table_Select</span> is primarily used to constrain and
                validate so that it may enforce the criteria for a legal <b><tt>SELECT</tt></b>
                query. However there may be certain cases where you require the flexibility of the
                <span class="classname">Zend_Db_Table_Row</span> component and do not require a writable or
                deletable row. for this specific user case, it is possible to retrieve a row or
                rowset by passing a <b><tt>FALSE</tt></b> value to
                 <span class="methodname">setIntegrityCheck()</span>. The resulting row or rowset will be
                returned as a &#039;locked&#039; row (meaning the  <span class="methodname">save()</span>,
                 <span class="methodname">delete()</span> and any field-setting methods will throw an
                exception).
            </p>

            <div class="example" id="zend.db.table.qry.rows.set.integrity.example"><div class="info"><p><b>Example #28 
                    Removing the integrity check on Zend_Db_Table_Select to allow JOINed rows
                </b></p></div>
                

                <pre class="programlisting brush: php">
$table = new Bugs();

$select = $table-&gt;select(Zend_Db_Table::SELECT_WITH_FROM_PART)
                -&gt;setIntegrityCheck(false);
$select-&gt;where(&#039;bug_status = ?&#039;, &#039;NEW&#039;)
       -&gt;join(&#039;accounts&#039;,
              &#039;accounts.account_name = bugs.reported_by&#039;,
              &#039;account_name&#039;)
       -&gt;where(&#039;accounts.account_name = ?&#039;, &#039;Bob&#039;);

$rows = $table-&gt;fetchAll($select);
</pre>

            </div>
        </div>
    </div>

    <div class="section" id="zend.db.table.fetch-row"><div class="info"><h1 class="title">Querying for a Single Row</h1></div>
        

        <p class="para">
            You can query for a single row using criteria similar to that of the
             <span class="methodname">fetchAll()</span> method.
        </p>

        <div class="example" id="zend.db.table.fetch-row.example1"><div class="info"><p><b>Example #29 Example of finding a single row by an expression</b></p></div>
            

            <pre class="programlisting brush: php">
$table = new Bugs();

$select  = $table-&gt;select()-&gt;where(&#039;bug_status = ?&#039;, &#039;NEW&#039;)
                           -&gt;order(&#039;bug_id&#039;);

$row = $table-&gt;fetchRow($select);
</pre>

        </div>

        <p class="para">
            This method returns an object of type <span class="classname">Zend_Db_Table_Row_Abstract</span>.
            If the search criteria you specified match no rows in the database table, then
             <span class="methodname">fetchRow()</span> returns <acronym class="acronym">PHP</acronym>&#039;s
            <b><tt>NULL</tt></b> value.
        </p>
    </div>

    <div class="section" id="zend.db.table.info"><div class="info"><h1 class="title">Retrieving Table Metadata Information</h1></div>
        

        <p class="para">
            The <span class="classname">Zend_Db_Table_Abstract</span> class provides some information about
            its metadata. The  <span class="methodname">info()</span> method returns an array structure with
            information about the table, its columns and primary key, and other metadata.
        </p>

        <div class="example" id="zend.db.table.info.example"><div class="info"><p><b>Example #30 Example of getting the table name</b></p></div>
            

            <pre class="programlisting brush: php">
$table = new Bugs();

$info = $table-&gt;info();

echo &quot;The table name is &quot; . $info[&#039;name&#039;] . &quot;\n&quot;;
</pre>

        </div>

        <p class="para">
            The keys of the array returned by the  <span class="methodname">info()</span> method are
            described below:
        </p>

        <ul class="itemizedlist">
            <li class="listitem">
                <p class="para">
                    <em class="emphasis">name</em> =&gt; the name of the table.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                    <em class="emphasis">cols</em> =&gt; an array, naming the columns of
                    the table.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                    <em class="emphasis">primary</em> =&gt; an array, naming the columns in
                    the primary key.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                    <em class="emphasis">metadata</em> =&gt; an associative array, mapping
                    column names to information about the columns. This is the information returned
                    by the  <span class="methodname">describeTable()</span> method.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                    <em class="emphasis">rowClass</em> =&gt; the name of the concrete class
                    used for Row objects returned by methods of this table instance. This defaults
                    to <span class="classname">Zend_Db_Table_Row</span>.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                    <em class="emphasis">rowsetClass</em> =&gt; the name of the concrete
                    class used for Rowset objects returned by methods of this table instance. This
                    defaults to <span class="classname">Zend_Db_Table_Rowset</span>.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                    <em class="emphasis">referenceMap</em> =&gt; an associative array, with
                    information about references from this table to any parent tables. See
                    <a href="zend.db.table.relationships.html#zend.db.table.relationships.defining" class="link">this chapter</a>.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                    <em class="emphasis">dependentTables</em> =&gt; an array of class names
                    of tables that reference this table. See
                    <a href="zend.db.table.relationships.html#zend.db.table.relationships.defining" class="link">this chapter</a>.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                    <em class="emphasis">schema</em> =&gt; the name of the schema (or
                    database or tablespace) for this table.
                </p>
            </li>
        </ul>
    </div>

    <div class="section" id="zend.db.table.metadata.caching"><div class="info"><h1 class="title">Caching Table Metadata</h1></div>
        

        <p class="para">
            By default, <span class="classname">Zend_Db_Table_Abstract</span> queries the
            underlying database for <a href="zend.db.table.html#zend.db.table.info" class="link">table
                metadata</a> whenever that data is needed to perform table
            operations. The table object fetches the table metadata from the
            database using the adapter&#039;s  <span class="methodname">describeTable()</span> method.
            Operations requiring this introspection include:
        </p>

        <ul class="itemizedlist">
            <li class="listitem"><p class="para"> <span class="methodname">insert()</span></p></li>
            <li class="listitem"><p class="para"> <span class="methodname">find()</span></p></li>
            <li class="listitem"><p class="para"> <span class="methodname">info()</span></p></li>
        </ul>

        <p class="para">
            In some circumstances, particularly when many table objects are instantiated against
            the same database table, querying the database for the table metadata for each instance
            may be undesirable from a performance standpoint. In such cases, users may benefit by
            caching the table metadata retrieved from the database.
        </p>

        <p class="para">
            There are two primary ways in which a user may take advantage of table metadata
            caching:
        </p>

        <ul class="itemizedlist">
            <li class="listitem">
                <p class="para">
                    <em class="emphasis">Call
                     <span class="methodname">Zend_Db_Table_Abstract::setDefaultMetadataCache()</span></em>
                    - This allows a developer to once set the default cache object to be used
                    for all table classes.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                    <em class="emphasis">Configure
                     <span class="methodname">Zend_Db_Table_Abstract::__construct()</span></em> -
                    This allows a developer to set the cache object to be used for a particular
                    table class instance.
                </p>
            </li>
        </ul>

        <p class="para">
            In both cases, the cache specification must be either <b><tt>NULL</tt></b> (i.e.,
            no cache used) or an instance of
            <a href="zend.cache.frontends.html#zend.cache.frontends.core" class="link"><span class="classname">Zend_Cache_Core</span></a>.
            The methods may be used in conjunction when it is desirable to have both a default
            metadata cache and the ability to change the cache for individual table objects.
        </p>

        <div class="example" id="zend.db.table.metadata.caching-default"><div class="info"><p><b>Example #31 Using a Default Metadata Cache for all Table Objects</b></p></div>
            

            <div class="example-contents"><p>
                The following code demonstrates how to set a default metadata cache to be used for
                all table objects:
            </p></div>

            <pre class="programlisting brush: php">
// First, set up the Cache
$frontendOptions = array(
    &#039;automatic_serialization&#039; =&gt; true
    );

$backendOptions  = array(
    &#039;cache_dir&#039;                =&gt; &#039;cacheDir&#039;
    );

$cache = Zend_Cache::factory(&#039;Core&#039;,
                             &#039;File&#039;,
                             $frontendOptions,
                             $backendOptions);

// Next, set the cache to be used with all table objects
Zend_Db_Table_Abstract::setDefaultMetadataCache($cache);

// A table class is also needed
class Bugs extends Zend_Db_Table_Abstract
{
    // ...
}

// Each instance of Bugs now uses the default metadata cache
$bugs = new Bugs();
</pre>

        </div>

        <div class="example" id="zend.db.table.metadata.caching-instance"><div class="info"><p><b>Example #32 Using a Metadata Cache for a Specific Table Object</b></p></div>
            

            <div class="example-contents"><p>
                The following code demonstrates how to set a metadata cache for a specific table
                object instance:
            </p></div>

            <pre class="programlisting brush: php">
// First, set up the Cache
$frontendOptions = array(
    &#039;automatic_serialization&#039; =&gt; true
    );

$backendOptions  = array(
    &#039;cache_dir&#039;                =&gt; &#039;cacheDir&#039;
    );

$cache = Zend_Cache::factory(&#039;Core&#039;,
                             &#039;File&#039;,
                             $frontendOptions,
                             $backendOptions);

// A table class is also needed
class Bugs extends Zend_Db_Table_Abstract
{
    // ...
}

// Configure an instance upon instantiation
$bugs = new Bugs(array(&#039;metadataCache&#039; =&gt; $cache));
</pre>

        </div>

        <blockquote class="note"><p><b class="note">Note</b>: <span class="info"><b>Automatic Serialization with the Cache Frontend</b><br /></span>
            

            <p class="para">
                Since the information returned from the adapter&#039;s
                 <span class="methodname">describeTable()</span> method is an array, ensure that the
                <span class="property">automatic_serialization</span> option is set to
                <b><tt>TRUE</tt></b> for the <span class="classname">Zend_Cache_Core</span> frontend.
            </p>
        </p></blockquote>

        <p class="para">
            Though the above examples use <span class="classname">Zend_Cache_Backend_File</span>, developers
            may use whatever cache backend is appropriate for the situation. Please see
            <a href="zend.cache.html" class="link">Zend_Cache</a> for more information.
        </p>

        <div class="section" id="zend.db.table.metadata.caching.hardcoding"><div class="info"><h1 class="title">Hardcoding Table Metadata</h1></div>
            

            <p class="para">
                To take metadata caching a step further, you can also choose to
                hardcode metadata. In this particular case, however, any changes
                to the table schema will require a change in your code. As such,
                it is only recommended for those who are optimizing for
                production usage.
            </p>

            <p class="para">
                The metadata structure is as follows:
            </p>

            <pre class="programlisting brush: php">
protected $_metadata = array(
    &#039;&lt;column_name&gt;&#039; =&gt; array(
        &#039;SCHEMA_NAME&#039;      =&gt; &lt;string&gt;,
        &#039;TABLE_NAME&#039;       =&gt; &lt;string&gt;,
        &#039;COLUMN_NAME&#039;      =&gt; &lt;string&gt;,
        &#039;COLUMN_POSITION&#039;  =&gt; &lt;int&gt;,
        &#039;DATA_TYPE&#039;        =&gt; &lt;string&gt;,
        &#039;DEFAULT&#039;          =&gt; NULL|&lt;value&gt;,
        &#039;NULLABLE&#039;         =&gt; &lt;bool&gt;,
        &#039;LENGTH&#039;           =&gt; &lt;string - length&gt;,
        &#039;SCALE&#039;            =&gt; NULL|&lt;value&gt;,
        &#039;PRECISION&#039;        =&gt; NULL|&lt;value&gt;,
        &#039;UNSIGNED&#039;         =&gt; NULL|&lt;bool&gt;,
        &#039;PRIMARY&#039;          =&gt; &lt;bool&gt;,
        &#039;PRIMARY_POSITION&#039; =&gt; &lt;int&gt;,
        &#039;IDENTITY&#039;         =&gt; &lt;bool&gt;,
    ),
    // additional columns...
);
</pre>


            <p class="para">
                An easy way to get the appropriate values is to use the metadata
                cache, and then to deserialize values stored in the cache.
            </p>

            <p class="para">
                You can disable this optimization by turning of the
                <span class="property">metadataCacheInClass</span> flag:
            </p>

            <pre class="programlisting brush: php">
// At instantiation:
$bugs = new Bugs(array(&#039;metadataCacheInClass&#039; =&gt; false));

// Or later:
$bugs-&gt;setMetadataCacheInClass(false);
</pre>


            <p class="para">
                The flag is enabled by default, which ensures that the
                <var class="varname">$_metadata</var> array is only populated once per
                instance.
            </p>
        </div>
    </div>

    <div class="section" id="zend.db.table.extending"><div class="info"><h1 class="title">Customizing and Extending a Table Class</h1></div>
        

        <div class="section" id="zend.db.table.extending.row-rowset"><div class="info"><h1 class="title">Using Custom Row or Rowset Classes</h1></div>
            

            <p class="para">
                By default, methods of the Table class return a Rowset in instances of the concrete
                class <span class="classname">Zend_Db_Table_Rowset</span>, and Rowsets contain a collection
                of instances of the concrete class <span class="classname">Zend_Db_Table_Row</span> You can
                specify an alternative class to use for either of these, but they must be classes
                that extend <span class="classname">Zend_Db_Table_Rowset_Abstract</span> and
                <span class="classname">Zend_Db_Table_Row_Abstract</span>, respectively.
            </p>

            <p class="para">
                You can specify Row and Rowset classes using the Table constructor&#039;s options array,
                in keys &#039;<span class="property">rowClass</span>&#039; and &#039;<span class="property">rowsetClass</span>&#039;
                respectively. Specify the names of the classes using strings.
            </p>

            <div class="example" id="zend.db.table.extending.row-rowset.example"><div class="info"><p><b>Example #33 Example of specifying the Row and Rowset classes</b></p></div>
                

                <pre class="programlisting brush: php">
class My_Row extends Zend_Db_Table_Row_Abstract
{
    ...
}

class My_Rowset extends Zend_Db_Table_Rowset_Abstract
{
    ...
}

$table = new Bugs(
    array(
        &#039;rowClass&#039;    =&gt; &#039;My_Row&#039;,
        &#039;rowsetClass&#039; =&gt; &#039;My_Rowset&#039;
    )
);

$where = $table-&gt;getAdapter()-&gt;quoteInto(&#039;bug_status = ?&#039;, &#039;NEW&#039;)

// Returns an object of type My_Rowset,
// containing an array of objects of type My_Row.
$rows = $table-&gt;fetchAll($where);
</pre>

            </div>

            <p class="para">
                You can change the classes by specifying them with the
                 <span class="methodname">setRowClass()</span> and  <span class="methodname">setRowsetClass()</span>
                methods. This applies to rows and rowsets created subsequently; it does not change
                the class of any row or rowset objects you have created previously.
            </p>

            <div class="example" id="zend.db.table.extending.row-rowset.example2"><div class="info"><p><b>Example #34 Example of changing the Row and Rowset classes</b></p></div>
                

                <pre class="programlisting brush: php">
$table = new Bugs();

$where = $table-&gt;getAdapter()-&gt;quoteInto(&#039;bug_status = ?&#039;, &#039;NEW&#039;)

// Returns an object of type Zend_Db_Table_Rowset
// containing an array of objects of type Zend_Db_Table_Row.
$rowsStandard = $table-&gt;fetchAll($where);

$table-&gt;setRowClass(&#039;My_Row&#039;);
$table-&gt;setRowsetClass(&#039;My_Rowset&#039;);

// Returns an object of type My_Rowset,
// containing an array of objects of type My_Row.
$rowsCustom = $table-&gt;fetchAll($where);

// The $rowsStandard object still exists, and it is unchanged.
</pre>

            </div>

            <p class="para">
                For more information on the Row and Rowset classes, see
                <a href="zend.db.table.row.html" class="link">this chapter</a> and <a href="zend.db.table.rowset.html" class="link">this one</a>.
            </p>
        </div>

        <div class="section" id="zend.db.table.extending.insert-update"><div class="info"><h1 class="title">Defining Custom Logic for Insert, Update, and Delete</h1></div>
            

            <p class="para">
                You can override the  <span class="methodname">insert()</span> and
                 <span class="methodname">update()</span> methods in your Table class. This gives you the
                opportunity to implement custom code that is executed before performing the database
                operation. Be sure to call the parent class method when you are done.
            </p>

            <div class="example" id="zend.db.table.extending.insert-update.example"><div class="info"><p><b>Example #35 Custom logic to manage timestamps</b></p></div>
                

                <pre class="programlisting brush: php">
class Bugs extends Zend_Db_Table_Abstract
{
    protected $_name = &#039;bugs&#039;;

    public function insert(array $data)
    {
        // add a timestamp
        if (empty($data[&#039;created_on&#039;])) {
            $data[&#039;created_on&#039;] = time();
        }
        return parent::insert($data);
    }

    public function update(array $data, $where)
    {
        // add a timestamp
        if (empty($data[&#039;updated_on&#039;])) {
            $data[&#039;updated_on&#039;] = time();
        }
        return parent::update($data, $where);
    }
}
</pre>

            </div>

            <p class="para">
                You can also override the  <span class="methodname">delete()</span> method.
            </p>
        </div>

        <div class="section" id="zend.db.table.extending.finders"><div class="info"><h1 class="title">Define Custom Search Methods in Zend_Db_Table</h1></div>
            

            <p class="para">
                You can implement custom query methods in your Table class, if you have frequent
                need to do queries against this table with specific criteria. Most queries can be
                written using  <span class="methodname">fetchAll()</span>, but this requires that you
                duplicate code to form the query conditions if you need to run the query in several
                places in your application. Therefore it can be convenient to implement a method in
                the Table class to perform frequently-used queries against this table.
            </p>

            <div class="example" id="zend.db.table.extending.finders.example"><div class="info"><p><b>Example #36 Custom method to find bugs by status</b></p></div>
                

                <pre class="programlisting brush: php">
class Bugs extends Zend_Db_Table_Abstract
{
    protected $_name = &#039;bugs&#039;;

    public function findByStatus($status)
    {
        $where = $this-&gt;getAdapter()-&gt;quoteInto(&#039;bug_status = ?&#039;, $status);
        return $this-&gt;fetchAll($where, &#039;bug_id&#039;);
    }
}
</pre>

            </div>
        </div>

        <div class="section" id="zend.db.table.extending.inflection"><div class="info"><h1 class="title">Define Inflection in Zend_Db_Table</h1></div>
            

            <p class="para">
                Some people prefer that the table class name match a table name in the
                <acronym class="acronym">RDBMS</acronym> by using a string transformation called
                <em class="emphasis">inflection</em>.
            </p>

            <p class="para">
                For example, if your table class name is &quot;BugsProducts&quot;, it would
                match the physical table in the database called &quot;bugs_products&quot;, if
                you omit the explicit declaration of the <var class="varname">$_name</var> class property.
                In this inflection mapping, the class name spelled in &quot;CamelCase&quot; format would be
                transformed to lower case, and words are separated with an underscore.
            </p>

            <p class="para">
                You can specify the database table name independently from the class name by
                declaring the table name with the <var class="varname">$_name</var> class property in each
                of your table classes.
            </p>

            <p class="para">
                <span class="classname">Zend_Db_Table_Abstract</span> performs no inflection to map the
                class name to the table name. If you omit the declaration of
                <var class="varname">$_name</var> in your table class, the class maps to a database table
                that matches the spelling of the class name exactly.
            </p>

            <p class="para">
                It is inappropriate to transform identifiers from the database, because this can
                lead to ambiguity or make some identifiers inaccessible. Using the
                <acronym class="acronym">SQL</acronym> identifiers exactly as they appear in the database makes
                <span class="classname">Zend_Db_Table_Abstract</span> both simpler and more flexible.
            </p>

            <p class="para">
                If you prefer to use inflection, then you must implement the transformation
                yourself, by overriding the  <span class="methodname">_setupTableName()</span> method in
                your Table classes. One way to do this is to define an abstract class that extends
                <span class="classname">Zend_Db_Table_Abstract</span>, and then the rest of your tables
                extend your new abstract class.
            </p>

            <div class="example" id="zend.db.table.extending.inflection.example"><div class="info"><p><b>Example #37 Example of an abstract table class that implements inflection</b></p></div>
                

                <pre class="programlisting brush: php">
abstract class MyAbstractTable extends Zend_Db_Table_Abstract
{
    protected function _setupTableName()
    {
        if (!$this-&gt;_name) {
            $this-&gt;_name = myCustomInflector(get_class($this));
        }
        parent::_setupTableName();
    }
}

class BugsProducts extends MyAbstractTable
{
}
</pre>

            </div>

            <p class="para">
                You are responsible for writing the functions to perform inflection transformation.
                Zend Framework does not provide such a function.
            </p>
        </div>
    </div>
</div>
        <hr />

            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.db.select.html">Zend_Db_Select</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.db.html">Zend_Db</a></span><br />
                        <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.db.table.row.html">Zend_Db_Table_Row</a></div>
                    </td>
                </tr>
            </table>
</td>
        <td style="font-size: smaller;" width="15%"> <style type="text/css">
#leftbar {
	float: left;
	width: 186px;
	padding: 5px;
	font-size: smaller;
}
ul.toc {
	margin: 0px 5px 5px 5px;
	padding: 0px;
}
ul.toc li {
	font-size: 85%;
	margin: 1px 0 1px 1px;
	padding: 1px 0 1px 11px;
	list-style-type: none;
	background-repeat: no-repeat;
	background-position: center left;
}
ul.toc li.header {
	font-size: 115%;
	padding: 5px 0px 5px 11px;
	border-bottom: 1px solid #cccccc;
	margin-bottom: 5px;
}
ul.toc li.active {
	font-weight: bold;
}
ul.toc li a {
	text-decoration: none;
}
ul.toc li a:hover {
	text-decoration: underline;
}
</style>
 <ul class="toc">
  <li class="header home"><a href="manual.html">Programmer's Reference Guide</a></li>
  <li class="header up"><a href="manual.html">Programmer's Reference Guide</a></li>
  <li class="header up"><a href="reference.html">Zend Framework Reference</a></li>
  <li class="header up"><a href="zend.db.html">Zend_Db</a></li>
  <li><a href="zend.db.adapter.html">Zend_Db_Adapter</a></li>
  <li><a href="zend.db.statement.html">Zend_Db_Statement</a></li>
  <li><a href="zend.db.profiler.html">Zend_Db_Profiler</a></li>
  <li><a href="zend.db.select.html">Zend_Db_Select</a></li>
  <li class="active"><a href="zend.db.table.html">Zend_Db_Table</a></li>
  <li><a href="zend.db.table.row.html">Zend_Db_Table_Row</a></li>
  <li><a href="zend.db.table.rowset.html">Zend_Db_Table_Rowset</a></li>
  <li><a href="zend.db.table.relationships.html">Zend_Db_Table Relationships</a></li>
  <li><a href="zend.db.table.definition.html">Zend_Db_Table_Definition</a></li>
 </ul>
 </td>
    </tr>
</table>

<script type="text/javascript" src="../js/shCore.js"></script>
<script type="text/javascript" src="../js/shAutoloader.js"></script>
<script type="text/javascript" src="../js/main.js"></script>

</body>
</html>